<% (display-partial "doctype") %>
<head>
	<% (display-partial "header") %>
</head>

<body>

<div id="wrap">
	<div id="header">
		<% (display-partial "navigation") %>	
		<div class="clear"></div>
	</div>

	<div id="content">
				
		<div class="title nomargin">
			<p><% (title "| Dragonfly web framework") %><p>
		</div>
		
		<h1>Templates</h1>
		<p class="extract">In Dragonfly, templates are files that have newLISP code embedded in them. This code is evaluated server-side, generating a final document that's presented to visitors.</p>

		<p>
			Templates can be anything, but usually they're html files with newLISP code embedded in them. When you download Dragonfly, take a look at the files in <span class="code">example-site/views</span>, those are all templates, but they're also referred to as <b>views</b>.
		</p>
		<p>
			The term "view" comes from the V in MVC (<a href="http://en.wikipedia.org/wiki/Model–view–controller">model-view-controller</a>), a paradigm that Dragonfly follows only loosely (notably missing the 'model' aspect).
		</p>
		<p>
			Views are typically used to represent the data of a <i>model</i>, but Dragonfly doesn't really care to enforce this (although you are certainly welcome to). In this document the term 'view' will be used to refer to templates in the directory specified by <span class="code">DF:VIEWS_PATH</span>.
		</p>
		<h2>Where routes come into the picture</h2>
		<p>
			<span class="code">Route.Static</span> (one of the <%(link_to "built-in routes" "dragonfly_routes")%>) contains by default two request transformations for handling views:
		</p>
		<pre class="textmate-source"><span class="source source_newlisp">    <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">string</span> <span class="entity entity_symbol entity_symbol_lisp">VIEWS_PATH</span> <span class="string string_quoted string_quoted_double string_quoted_double_lisp"><span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_begin punctuation_definition_string_begin_lisp">"</span>/<span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_end punctuation_definition_string_end_lisp">"</span></span> _<span class="entity entity_paren entity_paren_lisp">)</span>
    <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">string</span> <span class="entity entity_symbol entity_symbol_lisp">VIEWS_PATH</span> <span class="string string_quoted string_quoted_double string_quoted_double_lisp"><span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_begin punctuation_definition_string_begin_lisp">"</span>/<span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_end punctuation_definition_string_end_lisp">"</span></span> _ <span class="entity entity_symbol entity_symbol_lisp">VIEW_EXTENSION</span><span class="entity entity_paren entity_paren_lisp">)</span></span></pre>
		<p>
			The last transformation listed there is responsible for transforming a request to this URL:
		</p>
		<p><span class="code">http://rundragonfly.com/dragonfly_templates</span></p>
		<p>Into a request for this file:</p>
		<p><span class="code">/home/www/rundragonfly.com/views/dragonfly_templates.html</span></p>
		<p>All of the files handled by <span class="code">Route.Static</span> eventually get passed through the function <span class="code">eval-template</span>, which searches for any newLISP code between <span class="code">OPEN_TAG</span> and <span class="code">CLOSE_TAG</span> and evaluates it.</p>
		<h2>Writing templates</h2>
		<p>
			By default, the <span class="code">OPEN_TAG</span> is <span class="code">&lt;%</span> and the <span class="code">CLOSE_TAG</span> is <span class="code">%&gt;</span>. Let's say we want to create an HTML file that displays the current time on the server, we might go about it like this:
		</p>
<pre class="textmate-source html_doc"><span class="text text_html text_html_basic"><span class="meta meta_tag meta_tag_structure meta_tag_structure_any meta_tag_structure_any_html"><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&lt;</span><span class="entity entity_name entity_name_tag entity_name_tag_structure entity_name_tag_structure_any entity_name_tag_structure_any_html">html</span><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&gt;</span></span>
<span class="meta meta_tag meta_tag_structure meta_tag_structure_any meta_tag_structure_any_html"><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&lt;</span><span class="entity entity_name entity_name_tag entity_name_tag_structure entity_name_tag_structure_any entity_name_tag_structure_any_html">body</span><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&gt;</span></span>
    The time is: <span class="source source_newlisp source_newlisp_embedded source_newlisp_embedded_html">&lt;% <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">date</span><span class="entity entity_paren entity_paren_lisp">)</span> %&gt;</span>
<span class="meta meta_tag meta_tag_structure meta_tag_structure_any meta_tag_structure_any_html"><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&lt;/</span><span class="entity entity_name entity_name_tag entity_name_tag_structure entity_name_tag_structure_any entity_name_tag_structure_any_html">body</span><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&gt;</span></span>
<span class="meta meta_tag meta_tag_structure meta_tag_structure_any meta_tag_structure_any_html"><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&lt;/</span><span class="entity entity_name entity_name_tag entity_name_tag_structure entity_name_tag_structure_any entity_name_tag_structure_any_html">html</span><span class="punctuation punctuation_definition punctuation_definition_tag punctuation_definition_tag_html">&gt;</span></span></span></pre>
		<p>
			That, however, will result in a page that says:
		</p>
		<div class="resultbox">
			The time is: 
		</div>
		<p>
			That's because evaluated expressions do not output anything unless they call <span class="code">print</span> or <span class="code">println</span>. We can fix it by rewriting it like so:
		</p>
<pre class="textmate-source html_doc"><span class="text text_html text_html_basic">The time is: <span class="source source_newlisp source_newlisp_embedded source_newlisp_embedded_html">&lt;% <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">print</span> <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">date</span><span class="entity entity_paren entity_paren_lisp">))</span> %&gt;</span></span></pre>
		<div class="resultbox">
			The time is: <% (print (date)) %>
		</div>
		<p>
			You can append an equals sign after the <span class="code">OPEN_TAG</span> to achieve the same result in fewer keystrokes:
		</p>
		<pre class="textmate-source html_doc"><span class="text text_html text_html_basic">The time is: <span class="source source_newlisp source_newlisp_embedded source_newlisp_embedded_html">&lt;%= <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">date</span><span class="entity entity_paren entity_paren_lisp">)</span> %&gt;</span></span></pre>
		<div class="resultbox">
			The time is: <%= (date) %>
		</div>
		<p class="info"><b>INFORMATION</b><br/>You can use all functions from newLISP and Dragonfly (<%(link_to "api" "dragonfly_api")%>), as well as functions provided by <%(link_to "plugins" "dragonfly_plugins")%>.</p>
		<h2>Configuration</h2>
		<p>
			Below is a list of configuration parameters that you'll find in <b>config.lsp</b> related to templates.
		</p>
		<h3 class="param">OPEN_TAG</h3>
		<p>Default value: <span class="code"><b>"&lt;%"</b></span></p>
		<h3 class="param">CLOSE_TAG</h3>
		<p>Default value: <span class="code"><b>"%&gt;"</b></span></p>
		<h3 class="param">VIEWS_PATH</h3>
		<p>Default value: <span class="code"><b>(string DOCUMENT_ROOT "/views")</b></span></p>
		<p>
			The location of views (for use with 'display-view' function).
		</p>
		
		<h3 class="param">PARTIALS_PATH</h3>
		<p>Default value: <span class="code"><b>(string DOCUMENT_ROOT "/views/partials")</b></span></p>
		<p>
			The location of partials (for use with 'display-partial' function).
		</p>
		
		<h3 class="param">DEFAULT_VIEW</h3>
		<p>Default value: <span class="code"><b>"welcome"</b></span></p>
		<p>
			The default view (when a user visits '/') sans file extension.
		</p>
		
		<h3 class="param">VIEW_EXTENSION</h3>
		<p>Default value: <span class="code"><b>".html"</b></span></p>
		<p>
			Used by one of the transformations in <span class="code">Route.Static</span> so that a request to <span class="code">/welcome</span> loads the file <span class="code">/views/welcome.html</span>.
		</p>
		
		<% (display-partial "continue") %>
		
		<div class="line-dotted"></div>

		<% (benchmark-result) %>
		
		<div class="line-dotted"></div>
		
		
	</div><!-- END CONTENT -->
	
</div><!-- END WRAP -->
<% (display-partial "footer") %>

